# Cache - interface for media caches
# Copyright (C) 2007 Lauri Taimila
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

__licence__ = "GPLv2"
__copyright__ = "2007, Lauri Taimila"
__author__ = "Lauri Taimila <lauri@taimila.com>"

class Cache:
    """
    Cache interface. Defines interface for cache handling. This
    interface is implemented by VideoCache, MusicCache and
    ImageCache classes.
    """
    
    SLEEP_TIME_BETWEEN_FILES = 20 # MUST BE POSITIVE VALUE
    """
    How many milliseconds we should wait between files when adding to cache.
    This allows other threads to do their job and makes cache process lighter
    but also slower.
    """
    
    def clearCache(self):
        """
        Implement this method in deriving classes.
        
        This method removes the cache completely. It should be used when the
        cache needs to be rebuild from scratch.
        """
        pass
    
    def addFile(self, filename):
        """
        Implement this method in deriving classes.
        
        This method adds a new file to the cache. This method should get all
        metadata from the internet, create a thumbnail etc.
        """
        pass
        
    def removeFile(self, filename):
        """
        Implement this method in deriving classes.
        
        This method removes file from the cache. This also should remove all
        extrnal data like thumbnails.
        """
        pass
        
    def updateFile(self, filename):
        """
        Implement this method in deriving classes.
        
        This method is executed when a file, that is already in cache, changes.
        This can happen forexample if user uses some ID3-tag editor for audio
        files. This method should update cache and all metadata up-to-date.
        """
        pass
        
    def addDirectory(self, path):
        """
        Implement this method in deriving classes.
        
        This method adds a new directory to the cache. Sub directories are
        added recursively and all files in them.
        """
        pass
        
    def removeDirectory(self, path):
        """
        Implement this method in deriving classes.
        
        This method removes directory from the cache. Also removes all subdirectories
        and all files in them. This also should remove all extrnal data like thumbnails.
        """
        pass
        
    def updateDirectory(self, path):
        """
        Implement this method in deriving classes.
        
        This method is executed when a file, that is already in cache, changes.
        This can happen forexample if user uses some ID3-tag editor for audio
        files. This method should update cache and all metadata up-to-date.
        """
        pass
        
    def isDirectoryInCache(self, path):
        """
        Implement this method in deriving classes.
        
        This method returns True if given directory is in cache. Otherwise
        method returns False.
        """
        pass
        
    def isFileInCache(self, filename):
        """
        Implement this method in deriving classes.
        
        This method returns True if given file is in cache. Otherwise
        method returns False.
        """
        pass
        
    def isSupportedFormat(self, filename):
        """
        Returns true if cache can handle the given file. Otherwise returns false
        """
        pass
